# 消息接收
为获得企微推送的消息,云 BU 应用需要先在企微中台注册回调地址(API 或界面方式)。然后,消息处理会和上游的消息接收配合按注册信息将企微消息回调给云 BU 应用。
# 回调服务配置
接收事件之前,需要在中台注册回调配置,具体详见 API 章节。其中 token 和 encoding_aes_key 用于消息加密,加密算法与企微保持一致企微消息回调 (opens new window)。
# 回调服务需要实现的功能
# 1. 回调服务需要实现 HTTP POST 请求接收业务数据
假设企业的接收消息的 URL 设置为http://api.3dept.com。当用户触发回调行为时,企业微信会发送回调消息到填写的 URL,请求内容如下:
请求方式: POST
请求地址 : http://api.3dept.com/?msg_signature=ASDFQWEXZCVAQFASDFASDFSS×tamp=13500001234&nonce=123412323&corp_id=wx5823bf96d3bd56c7&app_id=39fdda6e-a341-5e67-e243-d4ec9da063b8
接收数据格式 :
JsDHxnNCKXXpL9wrdtlBTQVS9xDOrQlau4HZCT9Rs3aFvbEUyszc/wi3N0PksapRMOPzSTTucp6jfVncnBy3nVUpny3E9c+MacM9pUGZPSVwYmS1dAw6noBZp6FOcWt4EoNnDhmvZ2sODun4vIAnihlSm2oXKsJYX0tYskliA7oj/lEWRp1B5xIQns2pHAOp7Q6DSsqqzttsum4UCgaaq0IqcDbfDuKRO61zJhpcaZ3M5VQXQAUYqhl4Tx08d/gzgIs/KUfvdCpwf5XtZrTDHfLM+r8LR0x/dJ/aIU6vAvmmlDa5h445BF6y0m+/Lx3Foolqy6pcoFLnP1aNqICOELfc4Y+tblKbHQABlaxxX3WP+mBxqq7oClhUweO8TxVZ8kCaCnTellINSFWfjBeTrMV6VUb1bySscrwhM6Y0aFAffl65qmKbJJ07mUpYclB27mhYoy7M7PWryutMcPvsmKlCmZZt3MdVZ6kHAfC7X7zBqx0rBB2pKEpgSjoJz35KjcAb3uce+mADbyzwukxlN7rCD/aZfnr+AEiBr9616Ek=
使用解密功能解密后,会还原成企微推送的 xml 字符串:
<xml>
<ToUserName>toUser</ToUserName>
<FromUserName>sys</FromUserName>
<CreateTime>1403610513</CreateTime>
<MsgType>event</MsgType>
<Event>change_external_contact</Event>
<ChangeType>add_external_contact</ChangeType>
<UserID>zhangsan></UserID>
<ExternalUserID>woAJ2GCAAAXtWyujaWJHDDGi0mAAAA></ExternalUserID>
<State>teststate></State>
<WelcomeCode>WELCOMECODE></WelcomeCode>
</xml>
xml 里的或个属性与 企微接口中的属性保持一致,具体含义可以查看企微文档。
# 消息处理器开放 API
API 名称 | 定义 | 说明 |
---|---|---|
注册消息处理器 | 查看 | |
更新消息处理器 | 查看 | |
删除消息处理器 | 查看 | |
通过企微中台应用 id 获取消息处理器 | 查看 | |
通过企微中台组织代码获取消息处理器 | 查看 |
# 支持订阅的企微原生事件
事件名称 | 事件代码 |
---|---|
标签成员变更事件 | change_contact_update_tag |
企业客户标签创建事件 | change_external_tag_create |
企业客户标签变更事件 | change_external_tag_update |
企业客户标签删除事件 | change_external_tag_delete |
客户群创建事件 | change_external_chat_create |
客户群变更事件 | change_external_chat_add_member |
客户群解散事件 | change_external_chat_dismiss |
客户接替失败事件 | change_external_contact_transfer_fail |
删除跟进成员事件 | change_external_contact_del_follow_user |
外部联系人免验证添加成员事件 | change_external_contact_add_half_external_contact |
添加企业客户事件 | change_external_contact_add_external_contact |
编辑企业客户事件 | change_external_contact_edit_external_contact |
删除企业客户事件 | change_external_contact_del_external_contact |
成员关注事件 | subscribe |
进入应用 | enter_agent |
上报地理位置 | LOCATION |
异步任务完成事件推送 | batch_job_result |
扫码推事件的事件推送 | scancode_push |
扫码推事件且弹出“消息接收中”提示框的事件推送 | scancode_waitmsg |
弹出系统拍照发图的事件推送 | pic_sysphoto |
弹出拍照或者相册发图的事件推送 | pic_photo_or_album |
弹出微信相册发图器的事件推送 | pic_weixin |
弹出地理位置选择器的事件推送 | location_select |
点击菜单拉取消息的事件推送 | click |
点击菜单跳转链接的事件推送 | view |
审批状态通知事件 | open_approval_change |
任务卡片事件推送 | taskcard_click |
共享应用事件回调 | share_agent_change |
新增成员事件 | change_contact_create_user |
更新成员事件 | change_contact_update_user |
删除成员事件 | change_contact_delete_user |
新增部门事件 | change_contact_create_party |
更新部门事件 | change_contact_update_party |
删除部门事件 | change_contact_delete_party |
# 支持订阅的企微中台事件
事件名称 | 事件代码 |
---|---|
客户继承状态变更事件 | change_external_contact_transfer_status_change |
会话产生事件 | msgaudit_session_created |
会话 NLP 分析成功事件 | msgaudit_session_nlp_analysis_success |
聊天消息产生事件 | msgaudit_qw_msg_created |
新增公费电话记录事件 | change_dial_record_add |
更新公费电话记录事件 | change_dial_record_update |
渠道码变更事件 | change_channel_code |
客户信息变更事件 | change_customer_info_update |
客户发起咨询事件 | kf_msg_enter |
客户接入人工服务事件 | kf_msg_human_handle |
客户聊天消息产生事件 | kf_msg_create |
触发记录产生事件 | msgaudit_trigger_record_create |
# 客户继承状态变更事件
客户继承(离职继承、在职继承)所产生的客户接替状态变更事件,企微中台会向接入方推送该事件。
结构示例:
<xml>
<ToUserName>ww3e3e5b8f4aa4fd94</ToUserName>
<FromUserName>ewmp</FromUserName>
<CreateTime>1649494800</CreateTime>
<MsgType>event</MsgType>
<Event>change_external_contact</Event>
<ChangeType>transfer_status_change</ChangeType>
<UpdateType>on_job_inherit</UpdateType>
<Status>3</Status>
<TakeoverTime>1648806036</TakeoverTime>
<QwUserIdHandover>godfrey</QwUserIdHandover>
<QwUserIdTakerover>yuzhongjian</QwUserIdTakerover>
<QwExternalUserid>wm-TUtCAAA8MNXcGpHjLExE4MO6F9Jew</QwExternalUserid>
</xml>
参数说明:
参数 | 类型 | 说明 |
---|---|---|
ToUserName | string | 企业微信 CorpID |
FromUserName | string | 此事件该值固定为 ewmp,表示该消息由企微中台内部产生 |
CreateTime | int64 | 消息创建时间 (时间戳) |
MsgType | string | 消息的类型,此时固定为 event |
Event | string | 事件的类型,此时固定为 change_external_contact |
ChangeType | string | 此时固定为 transfer_status_change |
UpdateType | string | 变更分类,quit_inherit-离职继承,on_job_inherit-在职继承 |
Status | int32 | 接替状态, 1-接替完毕 2-等待接替 3-客户拒绝 4-接替成员客户达到上限 |
TakeoverTime | int64 | 接替客户的时间,如果是等待接替状态,则为未来的自动接替时间,时间戳 |
QwUserIdHandover | string | 企业原跟进成员的企微 UserID |
QwUserIdTakerover | string | 企业接替成员的企微 UserID |
QwExternalUserid | string | 客户的 userid,注意不是企业成员的帐号 |
# 会话产生事件
注册该事件订阅时需指定 app_id。
示例:
<xml>
<ToUserName>xxxxxxxx</ToUserName>
<FromUserName>ewmp</FromUserName>
<CreateTime>1649494800</CreateTime>
<MsgType>event</MsgType>
<Event>msgaudit_session</Event>
<ChangeType>created</ChangeType>
<AppId>xxxxxx</AppId>
<ChatId>xxxxxx</ChatId>
<SessionId>xxxxxx</SessionId>
<AgentId>1000110</AgentId>
<Repair>0</Repair>
</xml>
参数说明:
参数 | 类型 | 说明 |
---|---|---|
ToUserName | string | 企业微信 corp_id |
FromUserName | string | 此事件该值固定为 ewmp,表示该消息由企微中台内部产生 |
CreateTime | int64 | 消息创建时间 (时间戳) |
MsgType | string | 消息的类型,此时固定为 event |
Event | string | 事件的类型,此时固定为 msgaudit_session |
ChangeType | string | 此时固定为 created |
AppId | string | 企微中台应用 id |
ChatId | string | 聊天 id |
SessionId | string | 产生的会话 id |
AgentId | string | 企业微信应用 id |
Repair | int | 是否补数据:0-否,1-是 |
# 会话 NLP 分析成功事件
注册该事件订阅时需指定 app_id。
示例:
<xml>
<ToUserName>xxxx</ToUserName>
<FromUserName>ewmp</FromUserName>
<CreateTime>1649494800</CreateTime>
<MsgType>event</MsgType>
<Event>msgaudit_session</Event>
<ChangeType>nlp_analysis_success</ChangeType>
<AppId>xxxxxx</AppId>
<ChatId>xxxxxx</ChatId>
<SessionId>xxxxxx</SessionId>
<AgentId>1000110</AgentId>
</xml>
参数说明:
参数 | 类型 | 说明 |
---|---|---|
ToUserName | string | 企业微信 corp_id |
FromUserName | string | 此事件该值固定为 ewmp,表示该消息由企微中台内部产生 |
CreateTime | int64 | 消息创建时间 (时间戳) |
MsgType | string | 消息的类型,此时固定为 event |
Event | string | 事件的类型,此时固定为 msgaudit_session |
ChangeType | string | 此时固定为 nlp_analysis_success |
AppId | string | 企微中台应用 id |
ChatId | string | 聊天 id |
SessionId | string | 会话 id |
AgentId | string | 企业微信应用 id |
# 聊天消息产生事件
不包含 switch 类型消息,不包含机器人发送的、成员相互发送的消息。
示例:
<xml>
<ToUserName>xxxxxxxx</ToUserName>
<FromUserName>ewmp</FromUserName>
<CreateTime>1649494800</CreateTime>
<MsgType>event</MsgType>
<Event>msgaudit_qw_msg</Event>
<ChangeType>created</ChangeType>
<ChatId>xxxxxx</ChatId>
<ChatRecordId>xxxxxx</ChatRecordId>
</xml>
参数说明:
参数 | 类型 | 说明 |
---|---|---|
ToUserName | string | 企业微信 corp_id |
FromUserName | string | 此事件该值固定为 ewmp,表示该消息由企微中台内部产生 |
CreateTime | int64 | 消息创建时间 (时间戳) |
MsgType | string | 消息的类型,此时固定为 event |
Event | string | 事件的类型,此时固定为 msgaudit_qw_msg |
ChangeType | string | 此时固定为 created |
ChatId | string | 聊天 id |
ChatRecordId | string | 聊天消息记录 id |
# 公费电话拨打记录变更事件
公费电话拨打记录产生变更时(新增和更新),企微中台会向接入方推送该事件。
结构示例:
<xml>
<Event>change_dial_record</Event>
<ChangeType>change_dial_record_add</ChangeType>
<ToUserName>ww4044a793663ad2da</ToUserName>
<AppId>39fdf3a9-d89f-1fee-82cd-e12d78b15714</AppId>
<DialRecordId>3a05ebb3-a0ab-1d80-9efb-85348da2fc12</DialRecordId>
<CallerId>tianhy</CallerId>
<CallTime>1660215718</CallTime>
<CallType>1</CallType>
<TotalDuration>2</TotalDuration>
<CallerDuration>2</CallerDuration>
<CalleeMsg>
<CalleeId>tianhy</CalleeId>
<CalleeDuration>2</CalleeDuration>
</CalleeMsg>
<FromUserName>ewmp</FromUserName>
<CreateTime>1661845646</CreateTime>
<MsgType>event</MsgType>
</xml>
参数说明:
参数 | 类型 | 说明 |
---|---|---|
Event | string | 事件的类型,固定为 change_dial_record |
ChangeType | string | 公费电话新增(change_dial_record_add) + 公费电话更新(change_dial_record_update) |
ToUserName | string | 企业微信 CorpID |
AppId | string | 企微中台应用 ID |
DialRecordId | string | 企微中台公费电话记录唯一 id |
CallerId | string | 主叫用户的企微成员 ID |
CallTime | int64 | 主叫用户拨出时间的十位秒级时间戳 |
CallType | int32 | 通话类型,1-单人通话 2-多人通话 |
TotalDuration | int64 | 总通话时长,单位/分钟 |
CallerDuration | int64 | 主叫用户的通话时长,单位/分钟 |
CalleeMsg | object[] | 被叫用户的通话信息 |
CalleeMsg[0].CalleeId | string | 企业原跟进成员的企微 UserID |
CalleeMsg[0].CalleePhone | string | 企业原跟进成员的企微 UserID |
CalleeMsg[0].CalleeDuration | int64 | 企业原跟进成员的企微 UserID |
FromUserName | string | 此事件该值固定为 ewmp,表示该消息由企微中台事件消息 |
CreateTime | string | 消息创建时间 (时间戳) |
MsgType | string | 消息的类型,此时固定为 event |
# 渠道码变更事件
渠道码产生变更时(新增、更新、失效、删除),企微中台会向接入方推送该事件。
注意:失效和删除,企微码都会释放不能再扫了,但失效操作后企微中台还能查询到记录,删除操作则不能查询。
结构示例:
<xml>
<ToUserName>xxxxxxxx</ToUserName>
<FromUserName>ewmp</FromUserName>
<CreateTime>1649494800</CreateTime>
<MsgType>event</MsgType>
<Event>change_channel</Event>
<MsgType>event</MsgType>
<ChangeType>create</ChangeType>
<ChannelId>xxxxxx</ChannelId>
<EId>xxxxxx</EId>
<AppId>xxxxxx</AppId>
</xml>
参数说明:
参数 | 类型 | 说明 |
---|---|---|
ToUserName | string | 企业微信 corp_id |
FromUserName | string | 此事件该值固定为 ewmp,表示该消息由企微中台内部产生 |
CreateTime | int64 | 消息创建时间 (时间戳) |
MsgType | string | 消息的类型,此时固定为 event |
Event | string | 事件的类型,此时固定为 change_channel |
ChangeType | string | 变更类型:create-创建、update-更新、delete-删除、disable-失效 |
ChannelId | string | 渠道码 id |
EId | string | 中台企业 id |
AppId | string | 中台应用 id |
# 客户信息更新事件
客户信息产生变更时(更新),企微中台会向接入方推送该事件。
结构示例:
<xml>
<ToUserName>xxxxxxxx</ToUserName>
<FromUserName>ewmp</FromUserName>
<CreateTime>1649494800</CreateTime>
<MsgType>event</MsgType>
<Event>change_customer_info</Event>
<ChangeType>update</ChangeType>
<EId>xxxxxx</EId>
<AppId>xxxxxx</AppId>
<UserId>xxxxxx</UserId>
<ExternalUserId>xxxxxx</ExternalUserId>
<AddTag>xxxxxx</AddTag>
</xml>
参数说明:
参数 | 类型 | 说明 |
---|---|---|
ToUserName | string | 企业微信 corp_id |
FromUserName | string | 此事件该值固定为 ewmp,表示该消息由企微中台内部产生 |
CreateTime | int64 | 消息创建时间 (时间戳) |
MsgType | string | 消息的类型,此时固定为 event |
Event | string | 事件的类型,此时固定为 change_customer_info |
ChangeType | string | 变更类型:create-创建、update-更新、delete-删除、disable-失效 |
EId | string | 中台企业 id |
AppId | string | 中台应用 id |
UserId | string | 员工 id |
ExternalUserId | string | 外部联系人 id |
AddTagId | string | 外部联系人添加标签,多个使用英文逗号隔开 |
RemoveTagId | string | 外部联系人删除标签,多个使用英文逗号隔开 |
# 客户发起咨询事件
客户发起咨询客服时,企微中台会向接入方推送该事件。
结构示例:
<xml>
<ToUserName>xxxxxxxx</ToUserName>
<FromUserName>ewmp</FromUserName>
<Event>kf_msg</Event>
<ChangeType>enter</ChangeType>
<AppId>xxxx</AppId>
<MsgType>event</MsgType>
<KefuId>xxx</KefuId>
<ChannelId>xxxxx</ChannelId>
<ChannelType>1</ChannelType>
<QwExternalUserid>xxxx</QwExternalUserid>
<ExtParam>xxxxxx</ExtParam>
<CreateTime>1649494800</CreateTime>
</xml>
参数说明:
参数 | 类型 | 说明 |
---|---|---|
ToUserName | string | 企业微信 corp_id |
FromUserName | string | 此事件该值固定为 ewmp,表示该消息由企微中台内部产生 |
MsgType | string | 消息的类型,此时固定为 event |
Event | string | 事件的类型,固定为 kf_msg |
ChangeType | string | 变更类型:固定为 enter |
AppId | string | 中台应用 id |
KefuId | string | 客服账号 id |
ChannelId | string | 渠道 id |
ChannelType | int64 | 渠道类型:1-小程序、2-公众号、3-视频号、4-抖音、5-快手、6-其他 |
QwExternalUserid | string | 外部联系人 id |
ExtParam | string | 接入方自定义参数,json 字符串(可包含 unionid,手机号,接入方来源等) |
CreateTime | int64 | 消息创建时间 (时间戳) |
# 客户接入人工服务事件
客户转接人工时,企微中台会向接入方推送该事件。
结构示例:
<xml>
<ToUserName>xxxxxxxx</ToUserName>
<FromUserName>ewmp</FromUserName>
<Event>kf_msg</Event>
<ChangeType>human_handle</ChangeType>
<AppId>xxxx</AppId>
<MsgType>event</MsgType>
<ChannelId>xxxxx</ChannelId>
<ChannelType>1</ChannelType>
<KefuId>xxx</KefuId>
<QwExternalUserid>xxxx</QwExternalUserid>
<QwUserId>xxxx</QwUserId>
<ExtParam>xxxxxx</ExtParam>
<CreateTime>1649494800</CreateTime>
</xml>
参数说明:
参数 | 类型 | 说明 |
---|---|---|
ToUserName | string | 企业微信 corp_id |
FromUserName | string | 此事件该值固定为 ewmp,表示该消息由企微中台内部产生 |
Event | string | 事件的类型,固定为 kf_msg |
ChangeType | string | 变更类型:固定为 human_handle |
AppId | string | 中台应用 id |
MsgType | string | 消息的类型,此时固定为 event |
ChannelId | string | 渠道 id |
ChannelType | int64 | 渠道类型:1-小程序、2-公众号、3-视频号、4-抖音、5-快手、6-其他 |
KefuId | string | 客服账号 id |
QwExternalUserid | string | 外部联系人 id |
QwUserId | string | 接待人企微成员 id |
ExtParam | string | 接入方自定义参数,json 字符串 (可包含 unionid,手机号,接入方来源等) |
CreateTime | int64 | 消息创建时间 (时间戳) |
# 客服聊天消息产生事件
客户给成员发送消息,成员给客户发送消息时,企微中台会向接入方推送该事件。
结构示例:
<xml>
<ToUserName>xxxxxxxx</ToUserName>
<FromUserName>ewmp</FromUserName>
<Event>kf_msg</Event>
<ChangeType>create</ChangeType>
<AppId>xxxx</AppId>
<MsgType>event</MsgType>
<ChannelType>1</ChannelType>
<ChannelId>xxxxx</ChannelId>
<KefuId>xxx</KefuId>
<QwExternalUserid>xxxx</QwExternalUserid>
<QwUserId>xxxx</QwUserId>
<KefuMsgId>xxxx</KefuMsgId>
<SenderType>1</SenderType>
<ExtParam>xxxxxx</ExtParam>
<CreateTime>1649494800</CreateTime>
</xml>
参数说明:
参数 | 类型 | 说明 |
---|---|---|
ToUserName | string | 企业微信 corp_id |
FromUserName | string | 此事件该值固定为 ewmp,表示该消息由企微中台内部产生 |
Event | string | 事件的类型,固定为 kf_msg |
ChangeType | string | 变更类型:固定为 create |
AppId | string | 中台应用 id |
MsgType | string | 消息的类型,此时固定为 event |
ChannelId | string | 渠道 id |
ChannelType | int64 | 渠道类型:1-小程序、2-公众号、3-视频号、4-抖音、5-快手、6-其他 |
KefuId | string | 客服账号 id |
QwExternalUserid | string | 外部联系人 id |
QwUserId | string | 接待人企微成员 id |
KefuMsgId | string | 客服消息 id |
SenderType | int64 | 发送人类型:0-未知、1-成员、2-外部联系人、3-机器人 |
ExtParam | string | 接入方自定义参数,json 字符串(可包含 unionid,手机号,接入方来源等) |
CreateTime | int64 | 消息创建时间 (时间戳) |
# 触发记录产生事件
注册该事件订阅时需指定 app_id。
示例:
<xml>
<ToUserName>xxxxxxxx</ToUserName>
<FromUserName>ewmp</FromUserName>
<MsgType>event</MsgType>
<Event>msgaudit_trigger_record</Event>
<ChangeType>created</ChangeType>
<CreateTime>1649494800</CreateTime>
<AppId>xxxxxx</AppId>
<TriggerRecordId>xxxxxxxx</TriggerRecordId>
<TriggerRecodeType>xxxxxx</TriggerRecodeType>
</xml>
参数说明:
参数 | 类型 | 说明 |
---|---|---|
ToUserName | string | 企业微信 corp_id |
FromUserName | string | 此事件该值固定为 ewmp,表示该消息由企微中台内部产生 |
MsgType | string | 消息的类型,此时固定为event |
Event | string | 事件的类型,此时固定为 msgaudit_trigger_record |
ChangeType | string | 此时固定为 created |
CreateTime | int64 | 消息创建时间 (时间戳) |
AppId | string | 企微中台应用id |
TriggerRecordId | string | 触发记录id |
TriggerRecodeType | int32 | 触发记录类型(1-员工 2-客户) |
← 页面插件接入